ParcelLabel API
b4m-d9u/Download Dangerous Goods
Dangerous goods are for approved senders only. Refer to the relevant sections for information on Domestic and International Inbound to NZ (Offshore) label requests. This section covers Dangerous goods parameters and confirms the process to return a rendered Dangerous goods form.
- Validations
| Dangerous Goods Validations | Validation results |
| Dangerous_Goods(DG) not provided and add_ons is CPOLDG/IWOLDG or IWXOLDG in label request, then continue 'regular' label and empty dangerous goods form generation. | Label and DG form Generated. |
| Dangerous_Goods(DG) provided, but add_ons is not CPOLDG/IWOLDG or IWXOLDG, then return an error message. | Error message: "There has been an error processing your request. Dangerous Goods AddOn not provided. Please contact support." |
| Dangerous_Goods(DG) provided and invalid un_number provided, then return an error message. | Error message: "Invalid UN Number". |
| Dangerous_Goods(DG) provided and invalid hazard_class provided, then return an error message. | Error message: "Invalid hazard class". |
| Dangerous_Goods(DG) provided and invalid packing_group provided, then return an error message. | Error message: "Packing group must be one of these values: 'I, II, III, na, NA, n/a, N/A". |
| Dangerous_Goods(DG) provided and Dangerous_Goods(DG).items array contains more than 3 objects, then return an error message. | Error message: "Number of DG Items Limit Exceeded". |
Sample Request Domestic Dangerous goods
{
"account_number": "91327067",
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "Jason",
"sender_reference_2": "CC 52",
"paper_dimensions": {
"width_cm": 17.4,
"height_cm": 10,
"stationery_size": "A4"
},
"sender_details": {
"name": "John Doe",
"xphone": "1",
"email": "testsender@nzpost.co.nz",
"company_name": "Acme Corp",
"site_code": 96306
},
"pickup_address": {
"country_code": "NZ",
"address_id": 1945196
},
"receiver_details": {
"name": "Joe Receiver",
"xphone": "6490000002",
"email": "testreceiver@nzpost.co.nz"
},
"delivery_address": {
"is_collection": false,
"building_name": "Test Delivery Building Name",
"company_name": "Test Delivery Company Name",
"street": "204 Blueskin Road",
"suburb": "Brunswick",
"city": "Whanganui",
"country_code": "NZ",
"postcode": "4571",
"instructions": "Ask for John Smith at the reception."
},
"parcel_details": [
{
"service_code": "CPOLP",
"add_ons": [
"CPSR",
"CPOLDG"
],
"dangerous_goods": {
"items": [
{
"un_number": "3082",
"hazard_class": "9",
"proper_shipping_name": "Environmentally hazardous substance, liquid, n.o.s. (Amicarbazone, Propylene glycol)",
"packing_group": "III",
"number_and_type_packages": "3 x Plastic Jerricans",
"dg_weight": "64"
},
{
"un_number": "UN1993",
"hazard_class": "3",
"proper_shipping_name": "Flammable Liquid, n.o.s. (Benzene, 1,2,4-trimethyl)",
"packing_group": "III",
"number_and_type_packages": "3 x Plastic Jerricans",
"dg_weight": "21"
},
{
"un_number": "UN1950",
"hazard_class": "2.1",
"proper_shipping_name": "Aerosols",
"packing_group": "NA",
"number_and_type_packages": "1 x Fibreboard Box",
"dg_weight": "5"
}
],
"is_dglq": true,
"is_radioactive": false,
"flashpoint": "34",
"hazchem_code": "3YE",
"is_marine_pollutant": "Yes",
"additional_handling_information": "test additional handling information",
"signatory_name": "Test signatory name",
"signatory_emergency_phone_number": "111"
},
"return_indicator": "OUTBOUND",
"description": "LARGE",
"dimensions": {
"length_cm": 5.8,
"width_cm": 3,
"height_cm": 5.0,
"weight_kg": 3
}
}
]
}Sample Request International Inbound to NZ(Offshore)
{
"account_number": "91327067",
"carrier": "COURIERPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "Jason",
"sender_reference_2": "CC 52",
"paper_dimensions": {
"width_cm": 17.4,
"height_cm": 10,
"stationery_size": "A4"
},
"sender_details": {
"name": "John Doe",
"xphone": "1",
"email": "testsender@nzpost.co.nz",
"company_name": "XYZ Widget COmpany",
"site_code": 96306
},
"pickup_address": {
"country_code": "NZ",
"address_id": 1945196
},
"receiver_details": {
"name": "Joe Receiver",
"xphone": "6490000002",
"email": "testreceiver@nzpost.co.nz"
},
"delivery_address": {
"is_collection": false,
"building_name": "Test Delivery Building Name",
"company_name": "Test Delivery Company Name",
"street": "204 Blueskin Road",
"suburb": "Brunswick",
"city": "Whanganui",
"country_code": "NZ",
"postcode": "4571",
"instructions": "Ask for John Smith at the reception."
},
"parcel_details": [
{
"service_code": "IWXOLP",
"add_ons": [
"IWXOLDG"
],
"dangerous_goods": {
"items": [
{
"un_number": "UN3082",
"hazard_class": "9",
"proper_shipping_name": "Environmentally hazardous substance, liquid, n.o.s. (Amicarbazone, Propylene glycol)",
"packing_group": "III",
"number_and_type_packages": "3 x Plastic Jerricans",
"dg_weight": "64"
},
{
"un_number": "UN1993",
"hazard_class": "3",
"proper_shipping_name": "Flammable Liquid, n.o.s. (Benzene, 1,2,4-trimethyl)",
"packing_group": "III",
"number_and_type_packages": "3 x Plastic Jerricans",
"dg_weight": "21"
},
{
"un_number": "UN1950",
"hazard_class": "2.1",
"proper_shipping_name": "Aerosols",
"packing_group": "NA",
"number_and_type_packages": "1 x Fibreboard Box",
"dg_weight": "5"
}
],
"is_dglq": true,
"is_radioactive": false,
"flashpoint": "34",
"hazchem_code": "3YE",
"is_marine_pollutant": "Yes",
"additional_handling_information": "test additional handling information",
"signatory_name": "Test signatory name",
"signatory_emergency_phone_number": "111"
},
"return_indicator": "OUTBOUND",
"description": "LARGE",
"dimensions": {
"length_cm": 5.8,
"width_cm": 3,
"height_cm": 5.0,
"weight_kg": 3
}
}
]
}Response Parameters
| Field Name | Description | Mandatory |
| consignment_id | Unique identifier for the consignment if the request is successful. | Yes |
| message_id | A unique ID for the API call | Yes |
| success | Returns true if request is successful. Returns false if request is not successful. | Yes |
Sample Response
{
"consignment_id": "S3BGUH",
"message_id": "bb590940-97b5-11e9-813b-02168927813a",
"success": true
}Resource URL
UAT:
Download Dangerous Goods declaration within a consignment:
https://api.uat.nzpost.co.nz/ParcelLabel/v3/labels/{consignment_id}/DG/{parcel_no}Production:
Download Dangerous Goods declaration within a consignment:
https://api.nzpost.co.nz/ParcelLabel/v3/labels/{consignment_id}/DG/{parcel_no}Resource Description
To download a Dangerous Goods Form generated form within a consignment, set parcel_number parameter to the parcel number of the label. Dangerous Goods forms are only available for download of a consignment with status "Complete". Use Get Status of Labels resource to check the status of the consignment prior to download.
Resource Information
| Attribute | Detail |
|---|---|
| Response Format | |
| Requires Authentication | Yes |
| Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Request Parameters
| Field Name | Description | Mand | Example |
|---|---|---|---|
| consignment_id | The unique id of a consignment | Yes | 7EDZHE |
| page | The page number if download a label | Yes | 1 |
Sample Requests
Download a Dangerous Goods form generated within a consignment:
https://api.uat.nzpost.co.nz/ParcelLabel/v3/labels/6CW65J/DG/1Response
The Dangerous Goods form is returned in PDF.
Sample Response
Sample: Failure
{
"success": false,
"errors": [
{
"code": "40000",
"message": "Bad Request",
"details": "No DG Form Available"
}
],
"message_id": "fbfaf950-e8ad-11ef-8d86-020d66982371"
}